Skip to content

Add experimental C API and .NET packages for components - #564

Open
ludfjig wants to merge 3 commits into
mainfrom
hyperlight-0.18-capi
Open

ludfjig wants to merge 3 commits into
mainfrom
hyperlight-0.18-capi

Conversation

@ludfjig

@ludfjig ludfjig commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

.NET and other non-Rust hosts can't use hyperlight-wasm, because its host API is Rust only.

This adds an experimental C API and .NET packages on top of it:

  • hyperlight-wasm-capi is a C API for running components. Callers register host functions, load a component and call its functions. They can also snapshot, restore and interrupt a sandbox.
  • The C API works with any component, because it never decodes values. Callers pass each argument as a byte buffer in Hyperlight's component wire format and get the result back the same way. Generated bindings, such as the .NET ones, do the encoding.
  • Hyperlight.Wasm wraps the C API. Hyperlight.Wasm.Build generates typed C# bindings from WIT at build time. Its MSBuild task loads hyperlight-wasm-csharp-bindgen, a native library around Hyperlight's hyperlight-component-csharp, so builds need no Rust.

A guest runtime is built for one WIT world and is embedded when a Rust host builds. A non-Rust host has no Rust build to embed it in. So the C API loads the runtime from a file, through SandboxBuilder::with_runtime_file behind the experimental_runtime_file feature. Here users build that runtime with cargo hyperlight. #574 adds a tool and MSBuild support for it.

  • The hyperlight-wasm-runtime guest binary has an ELF section, .note_hyperlight_wasm_runtime, holding its crate version and a hash of its WIT world. The hash covers the WIT_WORLD file or directory and WIT_WORLD_NAME.
  • with_runtime_file rejects a guest binary whose crate version differs from the host's hyperlight-wasm crate version, because host and guest must agree on the guest ABI. The hyperlight-wasm build checks its embedded guest binary the same way.
  • A snapshot records the world hash of its guest binary. A host built with WIT_WORLD only loads snapshots with the same hash. A host built without one, like the C API, loads snapshots of any world, because it only uses guest binaries from files.
  • SandboxBuilder::with_interrupt_vcpu_sigrtmin_offset changes the interrupt signal, since .NET uses SIGRTMIN.

The C API and packages are versioned as experimental and not published yet. just dotnet-test and just examples-components run their tests, and CI runs both on every platform. On macOS the .NET tests run as a signed executable, because the dotnet host lacks the hypervisor entitlement.

@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch 4 times, most recently from fbcf9c8 to b91d23d Compare November 4, 2026 01:22
@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch from b91d23d to 214c584 Compare November 11, 2026 19:25
@ludfjig ludfjig added the kind/enhancement New feature or request label Nov 11, 2026
@ludfjig ludfjig changed the title hyperlight-wasm capi Add experimental C API and .NET packages for components Nov 11, 2026
@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch 10 times, most recently from 152740d to 0231892 Compare November 12, 2026 18:39
@ludfjig
ludfjig marked this pull request as ready for review November 12, 2026 20:31
@ludfjig
ludfjig added this pull request to stack #576 November 13, 2026 00:42
Comment thread .github/workflows/dep_rust.yml Resolved
Comment thread dotnet/Directory.Build.props Resolved
Comment thread dotnet/README.md Resolved
Comment thread dotnet/README.md Resolved
Comment thread dotnet/README.md Resolved
Comment thread src/hyperlight_wasm_bindgen/Cargo.toml Resolved
@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch 2 times, most recently from 1baa590 to 95f1991 Compare November 16, 2026 18:46
Comment thread .github/workflows/dep_rust.yml Outdated
run: just test ${{ matrix.config }} ${{ env.FEATURES }}
working-directory: ./src/hyperlight_wasm

# Runs before Test Examples, which replaces the native modules with

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is a bit confusing... are we using pully modules of .net?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, the .NET tests use the native component. This step runs before Test Examples, which overwrites it with the Pulley one. I reworded the comment.

Comment thread dotnet/README.md

`docs/component-wire-format.md` in hyperlight lists how WIT types map to C#.

## Guest runtime and components

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I wonder could we package this up in the hyperlight.wasm.build project tool too? so you don't have to do this out of band but as part of the build? (this could be a follow up)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just thinking of ways to simplify the expereince

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added in #574

Comment thread dotnet/README.md Outdated
codesign -f -s - --entitlements macos-entitlements.plist bin/Release/net8.0/osx-arm64/publish/MyApp
```

`dotnet MyApp.dll` and `dotnet test` run inside the `dotnet` host, so they cannot create sandboxes on macOS.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it technically possible to create a test exe?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed

}

#[test]
#[ignore = "needs a guest runtime built for the component_sample example world"]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

are we ignoring all these test?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only for plain cargo test, because they need a runtime built for the component_sample world. CI runs them with --include-ignored in just examples-components.

@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch from 95f1991 to 9fc835f Compare November 17, 2026 00:03
ArgumentNullException.ThrowIfNull(value);
lock (_entries)
{
_entries.Add(new Entry { Value = value, Lent = lent });

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks like we always add here and clear doesn't remove the values so this always grows _entries

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file is a copy of hyperlight's C# runtime, tracked in hyperlight-dev/hyperlight#2056

@simongdavies simongdavies left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

a few comments/questions.

I am not a fan of the with_runtime_file, it would be better if the runtime was either created at build time or the world was seperate

Comment on lines +81 to +93
/** Any error not covered by another kind. */
#define HLW_ERROR_OTHER 0
/**
* The sandbox is poisoned by an interrupted or failed guest call. Restore a
* snapshot to use it again.
*/
#define HLW_ERROR_POISONED 1
/** A guest call was interrupted with `hlw_interrupt_handle_kill`. */
#define HLW_ERROR_CANCELLED 2
/** The function is not valid in the sandbox's current state. */
#define HLW_ERROR_INVALID_STATE 3
/** An argument is invalid. */
#define HLW_ERROR_INVALID_ARGUMENT 4

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This approach for errors seems a little fragile/verbose to me since we are forcing consumers to check for an error and free it but there is no way of enforcing that (compiler warnings with [[nodiscard]], attribute((warn_unused_result)) etc.)

might be better to use a numerical error val and then store the details in TLS and overwrite on new error and document the restrictions , for the host it might be just better to have a retrun val that signifies error and then have the host func set result to an error struct/message in the case of an error , that way it would avoid the potnential isseu where a caller could allocate the error but never use it and leak.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think TLS would be overkill, I kept returned errors. Wasmtime's C API is similar. I added HLW_MUST_USE macro though so compilers warn when an error is ignored.

} hlw_buf;

/** Any error not covered by another kind. */
#define HLW_ERROR_OTHER 0

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this really only a host func error? should we have a generic host func error

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added HLW_ERROR_HOST_FUNCTION for calls and loads that fail because a host function failed.

Comment thread src/hyperlight_wasm_capi/src/lib.rs Outdated
std::ptr::null_mut()
}

/// Bytes borrowed from C.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit : dont think this comment is clear/true since its used as argument to host func, might be better to say somehting along the lines of "A borrowed, read-only byte buffer. Passing this value does not transfer ownership. Its validity period is specified by the function using it."

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

Comment thread src/hyperlight_wasm_capi/src/lib.rs Outdated
pub len: usize,
}

/// Bytes owned by this library.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: "A byte buffer whose storage is allocated by the library. Release its storage with hlw_buf_delete."

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

Comment thread src/hyperlight_wasm_capi/src/lib.rs Outdated
/// `result` must be the result slot passed to the running host function.
/// `data` must point to `len` readable bytes, or `len` must be zero.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn hlw_result_set(result: *mut hlw_result, data: *const u8, len: usize) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

consider replacing this with hlw_bytes?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

Comment thread src/hyperlight_wasm_capi/src/lib.rs Outdated
Comment on lines +635 to +636
data: *const u8,
len: usize,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

consider replacing this with hlw_bytes?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

Comment thread .github/workflows/dep_rust.yml Outdated
# Pulley ones. Skipped on macOS, where the tests run inside the dotnet
# host, which lacks the hypervisor entitlement.
- name: Set up .NET
if: runner.os != 'macOS'

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you can build you test project as an executable using apphost and then give that executable the entitlement so you can test on macOS see this

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

let path = path.as_ref();
if self.metadata.runtime_file {
return Err(new_error!(
"Snapshots of a sandbox with a runtime file cannot be saved"

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why is this?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed. It was limited since sandboxes created from file didn't know about their wits

@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch 2 times, most recently from 1d8d096 to 9db79f3 Compare November 17, 2026 19:33
@ludfjig

ludfjig commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor Author

I am not a fan of the with_runtime_file, it would be better if the runtime was either created at build time or the world was seperate

Agree, unfortunately only rust can create it at build time, not c#(c).

@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch 2 times, most recently from 1586dd4 to 0baba7a Compare November 17, 2026 21:39
The experimental_runtime_file feature adds
SandboxBuilder::with_runtime_file, which loads the guest runtime from
a file instead of the one built into the crate. A host built once can
then run components of any world whose runtime was built separately.

The runtime records its hyperlight-wasm version and a hash of its WIT
world in an ELF section. with_runtime_file rejects a runtime from
another version, and snapshots of the sandbox record the runtime's
world, so they can be saved and loaded. A host built without WIT_WORLD
has no bindings of its own, so it loads snapshots of any world.

SandboxBuilder::with_interrupt_vcpu_sigrtmin_offset changes the signal
that interrupts a running guest on Linux. Hosts such as .NET use
SIGRTMIN themselves.

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>
Add hyperlight-wasm-capi, a C library declared in
include/hyperlight_wasm.h. Callers register host functions, load a
component and call its functions. They can also snapshot, restore and
interrupt a sandbox. It is experimental and not published.

The C API works with any component, because it never decodes values.
Callers pass each argument as a byte buffer in hyperlight's component
wire format and get the result back the same way. Generated bindings,
such as the .NET ones, do the encoding. Host functions take up to 32
parameters. Calls from a host function into its own sandbox fail.

just examples-components runs its tests against the component_sample
example world.

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>
Hyperlight.Wasm runs components from .NET through the C API. WasmSandbox
registers host functions, loads components and calls them, with
snapshots, interrupts and CancellationToken support. Host exceptions
become the InnerException of the failed call. Their messages do not
reach the guest. The interrupt signal defaults to SIGRTMIN + 1, because
the .NET runtime suspends threads for garbage collection with SIGRTMIN.
With offset 0 a collection can hang.

Hyperlight.Wasm.Build generates C# bindings from HyperlightWit items at
build time. Its MSBuild task loads hyperlight-wasm-csharp-bindgen, a
native library around hyperlight's C# generator, so builds need no Rust.

Both packages are experimental and take the workspace version with a
preview suffix. They are not published yet.

just dotnet-test runs the tests against the component_sample example
world. CI runs them with the prebuilt component on every platform. The
tests build as an xUnit.net v3 executable, so macOS signs it with the
hypervisor entitlement and runs it directly. dotnet test would run them
inside the unsigned dotnet host. just dotnet-pack packs both packages
for the build machine's runtime identifier.

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>
@ludfjig
ludfjig force-pushed the hyperlight-0.18-capi branch from 0baba7a to c234b2f Compare November 17, 2026 22:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

kind/enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants